Date: 2002-01-14 11:49:06
In this technical article I analyse a phpGroupware application : the Notepad application.
****************************************
****************************************
* Analysing a phpGroupware Application *
****************************************
****************************************
This text was written on the basis of the NotePad application of phpGroupware version 0.9.12 by Jean-François Declercq. Everything I write about phpGroupware we be published under http://www.jfdeclercq.com/.
In order to understand phpGroupware and be able to write a new application for it, I will analyse one of its applications : the Notes application.
I will analyse these aspects :
* the database : What is the db schema of the Notes application ?
* the business logic : What are the objects that are involved ? How is the composition, editing, deleting, search and browse of Notes implemented (As of TODAY!!) ? How is it related to the phpGroupware framework
* the presentation layer : How are the templates ? Themes ?
* the framework integration aspects : what is the required application structure and files (Administration, Setup, About,...)
************
The database
************
Using phpMyAdmin I browsed the phpgroupware database. One good news is that the database looks simple.
The Notes application uses only one table : the phpgw_notes table. The fields of this table are the following :
* note_id int(20) auto_increment
* note_owner int(11)
* note_access varchar(7) ('public' or 'private')
* note_date int(11)
* note_category int(9)
* note_content text
We can see that a value exists to link the note to a note_owner. This represents a relationship with phpgw_accounts.
So, 2 relationships can be identified :
- note_owner to phpgw_accounts
- note_category to phpgw_categories
And that's what we have to know for the Notes... Maybe we will have to identify later the other standard phpGroupware tables.
******************
The Business Logic
******************
Now we will analyse how the application functions have been implemented in the Notepad application.
Here are the functions I identified :
* Add a new note
* Delete a note
* Modify a note
* Search for notes
* Browsing notes
---------------------------
Browing and Searching Notes
---------------------------
The main page of the phpGroupware Notepad allows to browse the user's notes. To do this, the page makes use of the note class (/notes/index.php, Line 67) :
$notes_list = $notes->read_notes($start,$limit,$search,$filter,$cat_id);
This method basically fetches the notes (/notes/inc/class.notes.inc.php, Line 85) :
$sql = "SELECT * FROM phpgw_notes WHERE $filtermethod $searchmethod ORDER BY note_date DESC";
Note 1 : Unfortunately This is the only function actually implemented in the Notes class. If you have a look at some other classes (like 'bookmarks' or 'todo' or 'contacts') you will see that the add, delete and update methods are available at the class level meaning that these functionalities would be easier to reuse (adding a Note from an other phpGroupware application requires to find the INSERT statement in the code).
------------
Adding Notes
------------
The logic of adding a Note is in the add.php web page. This part of the code performs the insert in the Notes table (/notes/add.php, Line 78):
$phpgw->db->query("INSERT INTO phpgw_notes (note_owner,note_access,note_date,note_content,note_category) VALUES ('$accountid','$access','$time','$note','$cat_id')");
Note 2 : In order to have the logic reusable, the content of the 'if($addnote)' could just be
$notes->add($accountid,$access,$time,$note,$cat_id);
and the method would be implemented by cut&paste.
I know I'm a bit criticizing but It's because I'd like to be able to reuse the Notes application completely for my own application.
----------------------------
Deleting and Modifying Notes
----------------------------
The logic of deleting and modifying Notes are respectively in /notes/delete.php and /notes/edit.php. These use exactly the same programming structure as for adding notes.
******************
Presentation Logic
******************
----------------------
Treating incoming data
----------------------.
The first part of the presentation Logic concerns the management of incoming data. This is not complex with PHP as the incoming parameters can be treated directly as php variables. The tretment of this incoming data defines the action(s) to perform.
----------------
Use of templates
----------------.
The second part of the Presentation Logic is to display information. The Notes application uses multiple templates. You will find these under /notes/inc/templates/default/*.tpl.
If you want to see how a template looks like, you can htmlize these (On Win2000, just copy a template and rename it with a .html extension and IE5 will display it...)
The main template is the list.tpl template.
The first step is to create a template (/notes/index.php, Lines 21-24 ) :
$t = CreateObject('phpgwapi.Template',PHPGW_APP_TPL);
$t->set_file(array( 'notes_list_t' => 'list.tpl','notes_list' => 'list.tpl'));
$t->set_block('notes_list_t','notes_list','list');
Rem : I don't know yet what blocks are and what they are for.
Instructions to fill the template afterwards look like this (/notes/index.php, Lines 21-24 ):
$t->set_var('actionurl',$phpgw->link('/notes/index.php'));
*****************************
Framework integration aspects
*****************************
TBD. (I would need to find an overview of the phpgwAPI).
***********
Conclusions
***********
The notes application is a simple application that can be used to help understand how to write an application for phpGroupware.
One can identify the classical pattern of building web based applications. A phpGroupware application page can be written using this structure :
1. INPUT : Treat incoming parameters and values and decide next action(s)
2. ACTION : Use objects to execute action(s) (computing or DB actions) and get return values and results
3. REACTION : Based on return values, instanciate and fill in the right templates
4. OUTPUT = Parse all templates, send the page
In the actual code of Notes, the parts 1,2 and 3 are often mixed.
In the ACTION part, objects are called in order to execute the database or the computing parts of the job. Sometimes this logic is well encapsulated in a class (Notes browsing), sometimes not (adding Notes).
Some phpGroupware Invariants are used in the Notepad scripts :
- header.inc.php
- link()
- templates
- ACLs
- nextmatch (browsing pattern)
- categories
- preferences hook
- admin hook
*********
Follow Up
*********
- Continue Hello with a phpgw_hello table.
- Add browing capablilities to hello.
- Add lang() to hello.
- Add admin and prefs hooks for hello.
- Apply structue 1-4 to hello
- Add Setup hooks to hello (create tables statements)
-
*********
Questions
*********
- What is a block ?
- set of standard phpGroupware tables ?
- multi-lines templates ? How does it work ?
- there is JavaDoc --> is there a phpDoc ??
- checkPerms ?
